<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!--
Not Automatically generated, changed!:
$Id: script_ref_execution_model_eval_scripts.htm,v 1.2 2011/04/29 20:11:14 wilbertd Exp $ 
-->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Scripting reference - The script execution model - Evaluation of runtime
scripts</title>
<link rel="stylesheet" type="text/css" href="../avisynth.css">
</head>
<body>
<h2>The script execution model - Evaluation of runtime scripts</h2>
<p>Evaluation of runtime scripts starts, as already stated, at the frame serving
phase of the main script's execution. At that point frames of the final output
clip are requested by the host video application. This triggers a sequence of
successive calls to the GetFrame / GetAudio methods of all filters along the
filter graph. Whenever one of those filters is a runtime filter, the following
three-phase sequence of events happens <i>in every frame</i>:</p>
<ul>
  <li>Runtime environment initialisation.</li>
  <li>Runtime script parsing and evaluation.</li>
  <li>Runtime environment cleanup and delivery of the resulting frame.</li>
</ul>
<p>The following paragraphs examine each phase in more detail.</p>
<h2>Contents</h2>
<ul>
  <li class="toclevel-1"><span class="tocnumber"><a href="#Runtime_environment_initialisation">1</a></span> <a href="#Runtime_environment_initialisation"> <span class="toctext">Runtime
    environment initialisation</span></a></li>
  <li class="toclevel-1"><a href="#Runtime_script_parsing_and_evaluation"><span class="tocnumber">2</span>
    <span class="toctext">Runtime script parsing and evaluation</span></a></li>
  <li class="toclevel-1"><a href="#Runtime_environment_cleanup_and_delivery_of_the_resulting_frame"><span class="tocnumber">3</span>
    <span class="toctext">Runtime environment cleanup and delivery of the
    resulting frame</span></a></li>
  <li class="toclevel-1"><a href="#The_runtime_environment_in_detail"><span class="tocnumber">4</span>
    <span class="toctext">The runtime environment in detail</span></a>
    <ul>
      <li class="toclevel-2"><a href="#Elements_of_the_runtime_environment"><span class="tocnumber">4.1</span>
        <span class="toctext">Elements of the runtime environment</span></a></li>
      <li class="toclevel-2"><a href="#Runtime_functions_and_current_frame"><span class="tocnumber">4.2</span>
        <span class="toctext">Runtime functions and current_frame</span></a></li>
      <li class="toclevel-2"><a href="#Checklist_for_developing_correct_runtime_scripts"><span class="tocnumber">4.3</span>
        <span class="toctext">Checklist for developing correct runtime scripts</span></a></li>
    </ul>
  </li>
</ul>
<a name="Runtime_environment_initialisation"></a>
<h3><span class="mw-headline">Runtime environment initialisation</span></h3>
<p>The runtime filter code sets (at the top-level script local scope) its <a href="syntax_runtime_environment.htm" title="Runtime environment">special
variables</a> for the runtime script. These at the minimum include <tt>last</tt>,
which is set to the filter's source clip and <tt>current_frame</tt>, which is
set to the frame number requested by the filter from the AviSynth code.</p>
<p>As a consequence, those special variables <i>cannot</i> be passed between
runtime scripts; whatever value the passing script will set, it will be
overwritten by the receiving filter's frame initialisation code.</p>
<a name="Runtime_script_parsing_and_evaluation"></a>
<h3><span class="mw-headline">Runtime script parsing and evaluation</span></h3>
<p>The runtime script is parsed, as a regular script would be parsed if loaded
in AviSynth. The parsing mechanism is the same. Thus <i>everything</i> allowed
to a regular script is allowed to a runtime script; <i>what changes is the
context of execution</i>. For example, you can:</p>
<ul>
  <li>Use <b>multi-line scripts</b>; they just have to be contained inside a
    three-double-quotes pair (this is a requirement only if string literals are
    used inside the script, else single double quotes can be used also).</li>
  <li>Define / assign variables, both local and global.</li>
  <li><a href="corefilters/import.htm" title="Import">Import</a>
    other scripts and/or load plugins and/or define functions.</li>
  <li>Call functions and filters.</li>
  <li>Use <a href="script_ref_arrays.htm" title="Arrays">arrays</a>
    and <a href="script_ref_block_statements.htm" title="Block statements">block
    statements</a>.</li>
  <li>Use <a href="syntax_control_structures.htm" title="Control structures">control
    structures</a>.</li>
</ul>
<p>Of course, some of the above are <b>not advisable</b>, because the different
execution context poses different constrains regarding performance and resource
usage. The main rule of thumb here is: <b>Parsing occurs in every frame
requested. Therefore, computationally expensive actions should be avoided</b>.
More on the <a href="script_ref_execution_model.htm" title="The script execution model">performance
considerations</a> section.</p>
<a name="Runtime_environment_cleanup_and_delivery_of_the_resulting_frame"></a>
<h3><span class="mw-headline">Runtime environment cleanup and delivery of the
resulting frame</span></h3>
<p>The runtime filter code receives the result of script parsing and evaluation.
If all went well, the result will be a valid filter graph (the runtime filter
graph) from which the runtime filter requests to fetch the needed frame. If not,
the filter will propagate the error to the caller. When the filter's code will
return the final video frame, the runtime filter graph will be destroyed. As
part of the cleanup the runtime filter code also restores the <tt>last</tt>
special variable to its previous value.</p>
<a name="The_runtime_environment_in_detail"></a>
<h3><span class="mw-headline">The runtime environment in detail</span></h3>
<p>Despite the very thin layer of added features (just a handful of variables
and functions) the runtime environment is much more dynamic that the normal
(main) script environment. The <i>key-difference</i> is the event-driven model
of runtime script execution as opposed to the linear flow of the main script's
execution. Execution of a runtime script occurs only in the event of a frame
request. In addition, since intermediate filters in the chain may shuffle and
combine frames in an arbitrary fashion, the requested frame's number may be
different than the final clip's frame number.</p>
<a name="Elements_of_the_runtime_environment"></a>
<h4><span class="mw-headline">Elements of the runtime environment</span></h4>
<p>At any time during the frame serving phase, the elements of the runtime
environment are the following:</p>
<ul>
  <li>The environment inherited by the main script's parsing phase, that is the
    main script's top-level local variables, the global variables and all
    imported script and plugin functions.</li>
  <li>The <a href="syntax_runtime_environment.htm" title="Runtime environment">special
    variables</a> set on every frame by the runtime filter initialisation code (<tt>last</tt>,
    <tt>current_frame</tt>, etc.)</li>
  <li>A set of <a href="syntax_internal_functions_runtime.htm" title="Internal functions/Runtime functions">runtime
    functions</a> to assist common information extraction operations.</li>
  <li>The environment created by the successive evaluation of runtime scripts
    triggered by all the final output clip's frames that have been requested so
    far by the host video application. This may include modifications to the
    environment inherited by the parsing phase such as change of variables'
    values, as well as addition of new locals and globals.</li>
</ul>
<a name="Runtime_functions_and_current_frame"></a>
<h4><span class="mw-headline">Runtime functions and current_frame</span></h4>
<p>An interesting feature of <a href="syntax_internal_functions_runtime.htm" title="Internal functions/Runtime functions">runtime
functions</a> is that they consult the value of the <tt>current_frame</tt>
special variable in order to determine what frame of their input clip(s) to
inspect for extracting information. This provides the ability inside a runtime
script to easily request information for <i>any</i> frame of a clip by changing
before the call to the function the <tt>current_frame</tt> variable.</p>
<p>As explained above,
setting the <tt>current_frame</tt> variable has no effect on other runtime
scripts in the filter chain because the runtime filters' initialisation code
resets <tt>current_frame</tt> to the proper value before executing the runtime
script. It also has no effect on subsequent filter calls in the runtime script.
But it does have on runtime functions and anywhere the value of <tt>current_frame</tt>
is used. Therefore, after such a usage it is good practice to restore the
variable to its initial value before issuing other script commands.</p>
<p>A skeleton example of a runtime script that computes a weighted second order
luma interpolation value (the actions after the computation are omitted)
follows:</p>
<pre>...previous processing omitted...
<a href="corefilters/conditionalfilter.htm" title="ScriptClip">ScriptClip</a>(&quot;&quot;&quot;  # this is a multiline string
    n = current_frame
    lm_k = <a href="syntax_internal_functions_runtime.htm" title="Internal functions/Runtime functions">AverageLuma</a>()
    current_frame = n - 1
    lm_km1 = AverageLuma()
    current_frame = n + 1
    lm_kp1 = AverageLuma()
    dvg = (lm_km1 - 2 * lm_k + lm_kp1) / 2
    lm_ipl = lm_k + <a href="syntax_internal_functions_numeric.htm">Sign</a>(dvg) * <a href="syntax_internal_functions_numeric.htm">Sqrt</a>(<a href="syntax_internal_functions_numeric.htm">Abs</a>(dvg))
    current_frame = n # remember to reset current_frame
    ...rest of script omitted...
    &quot;&quot;&quot;)
...subsequent processing omitted...</pre>
<a name="Checklist_for_developing_correct_runtime_scripts"></a>
<h4><span class="mw-headline">Checklist for developing correct runtime scripts</span></h4>
<p>Despite the dynamic nature of the runtime environment, creating runtime
scripts is relatively easy if you follow a simple set of rules:</p>
<ul>
  <li>Remember that your input (source) clip is stored upon start of script
    execution in the <tt>last</tt> special variable.</li>
  <li>If you assign temporary clips to variables, remember to set <tt>last</tt>
    at the end or issue a <tt>return</tt> statement.</li>
  <li>Do not change (with respect to the source clip of the filter) the
    dimensions, colorspace or framerate of the final result.</li>
  <li>Do not assume - unless there is a <b>very</b> compelling
    performance-related reason- a particular ordering of frame requests; try to
    build ordering-neutral scripts, that depend only on <tt>current_frame</tt>.</li>
  <li>Inspect the names of all input variables (ie those variables that are <i>not
    initialised</i> to a value inside the runtime script) of your runtime
    scripts to ensure that they are not overridden accidentally by a normal, not
    used for inter-script communication variable in any runtime script along the
    chain.</li>
  <li>In particular, avoid putting inside <a href="syntax_userdefined_scriptfunctions.htm" title="Script functions">functions</a>
    calls to runtime filters that share state between invocations or with other
    filters through variables; it is easy to forget that <i>you may only call
    the function once</i>, else you will end up with multiple filters that share
    <i>the same</i> variables, thus with a bug in your script.</li>
</ul>
<dl>
  <dd>In view of the above, runtime filters should be used in functions only if
    they either:
    <ul>
      <li>do not share state between invocations or with other filters through
        variables, or</li>
      <li>the function code takes care to create <i>unique names </i>of all the
        runtime script's shared variables on each function invocation.</li>
    </ul>
  </dd>
  <dd>A way to avoid variables is to dynamically build the runtime script using
    string concatenation and assign the related arguments' values to local
    variables in the runtime script. See the example code of the <a href="script_ref_execution_model_lifetime_variables.htm" title>bracket_luma</a>
    function.</dd>
</dl>
<hr>
<p>Back to the <a href="script_ref_execution_model.htm" title="The script execution model">script
execution model</a>.</p>
<p><kbd>$Date: 2011/04/29 20:11:14 $</kbd></p>
</body>
</html>
